[TDR Generic Table][Java SDK] Auto-increment of Fields in A Record

1. Interface Description

Add or subtract the value of the numeric Value field of the data with the specified Key in the table. TCAPLUS_CMD_INCREASE_REQ makes fields auto-increment. If multiple gamesvrs are initiated at the same time, they will auto increment multiple times and return the auto increment ID. The version number can be set to increment automatically. It is valid as long as it is set. If the version number is not specified, it can be ignored and directly incremented.

• Note:
• 1. Each auto-increment request always returns the current value + 1. Since auto-increment and return are original sub-operations, they do not cross with other requests
• 1. Update the value (auto-increment or auto-decrement) of the specified field according to the primarykey, only for numeric type fields. For example: The original value of pay.method is 200. If the requested value is 50, the final value is 250; If the requested value is -50, the final value is 150. Auto-decrement is only applicable to signed fields, such as int32 and int64.
• 3.Increment operation: If the upper and lower limits are not defined in the API, it will automatically reset to 0 when reaching the maximum or minimum value. However, you can define the upper and lower limits (upper_limit, lower_limit), and an overflow error will be reported.

2. Version Requirements

This interface is provided in all versions without special requirements.

3. Preparations

Refer to Preparation document to complete the preparation before using this interface and create the following TDR Generic table.

Get the following information after the preparation. These details will be used by the SDK:

1. Directory server address list
2. App ID
3. App access password
4. Game zone ID
5. Table name

4. Example Code

Basic execution process of example code:

1. Create a client;
2. Create a request;
3. Send a request;
4. Process the response;
5. Destroy the client.

4.1 Example Code for Synchronous Call

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. Prepare the environment information
        // 1.1. Directory server address list
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. App ID
        int appId = 1;
        // 1.3. App password
        String appPassword = "****************";
        // 1.4. Table group ID
        int tableGroupId = 1;
        // 1.5. Table name
        String tableName = "test";

        // 2. Create a client
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
            // 3. Construct a request to increase or decrease field values
            // 3.1. Get the request object. In order to improve the SDK's performance, the Request object is reused
            Request request = client.acquireRequest();
            // 3.2. Set the request type and target table name
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INCREASE_REQ);
            request.setTableName(tableName);
            // 3.3. Set the value of each Key field. Description: The value of the Key field cannot be updated
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            record.setKeyInt("itemid", 1);
            record.setKeyString("name", "test");
            // 3.4. Set the value to be increased or decreased for each Value field. A positive value indicates an increase, and a negative value indicates a decrease
            // Note: This operation can only be performed on numeric fields
            record.setValueByte("typeid", (byte) 1);

            // 4. Send a request and get the result
            Response response = client.poll(request);

            // 5. Process the result
            if (response.getResult() == 0) {
                // Field value increasing or decreasing successful
                // TODO: add the code to process the result of field value increasing or decreasing successful here
            } else {
                // Field value increasing or decreasing failure
                // TODO: add the code to process the result of field value increasing or decreasing failure here
            }
        } finally {
            // 6. Destroy the client object
            ClientFactory.destroyClient(client);
        }
    }

}

4.2 Example Code for Asynchronous Call

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. Prepare the environment information
        // 1.1. Directory server address list
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. App ID
        int appId = 1;
        // 1.3. App password
        String appPassword = "****************";
        // 1.4. Table group ID
        int tableGroupId = 1;
        // 1.5. Table name
        String tableName = "test";

        // 2. Create a client
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
            // 3. Construct a request to increase or decrease field values
            // 3.1. Get the request object. In order to improve the SDK's performance, the Request object is reused
            Request request = client.acquireRequest();
            // 3.2. Set the request type and target table name
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INCREASE_REQ);
            request.setTableName(tableName);
            // 3.3. Set the value of each Key field. Description: The value of the Key field cannot be updated
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            record.setKeyInt("itemid", 1);
            record.setKeyString("name", "test");
            // 3.4. Set the value to be increased or decreased for each Value field. A positive value indicates an increase, and a negative value indicates a decrease
            // Note: This operation can only be performed on numeric fields
            record.setValueByte("typeid", (byte) 1);

            CountDownLatch latch = new CountDownLatch(1);

            // 4. Send the request asynchronously and specify the processor that returns the response. The post method will return the result immediately
            client.post(request, new Future() {

                @Override
                public void onResponse(Response response) {
                    // 5. Process the response
                    if (response.getResult() == 0) {
                        // Data getting success
                        // TODO: add the subsequent processing code of successful data getting here
                    } else {
                        // Data getting failure
                        // TODO: add the subsequent processing code of failed data getting here
                    }
                }

            });

            latch.await();
        } finally {
            // 6. Destroy the client object
            ClientFactory.destroyClient(client);
        }
    }

}

5. Method Description in Request Object

Note: If there is an unlisted Request object method, it means that the method is invalid in the scenario of adding or subtracting field values.

5.1. Method Description in Data Object

Note: If there is an unlisted Record object method, it means that the method is invalid in the scenario of adding or subtracting field values.

6. Method Description in Response Object

Note: If there is an unlisted Response object method, it means that the method is invalid in the scenario of adding or subtracting field values.

7. FAQ

For details, see Meaning and Handling of Error Codes.

8. Other Reference Documents

[TDR Generic Table][C++ SDK] Interface Description for Auto-increment of Fields.

[TDR Generic Table] [Java SDK] Interface Description for Auto-increment of Part Fields.

[TDR Generic Table] [MySQL Protocol Compatibility Interface] Interface Description for Updating a Record